Thanks for the PR @AndyButland !

While I think this is very valuable information, I'm concerned about adding it to an already very long article.
Perhaps we could add this information into the "Expandables", like the ones we use in the Breaking Changes section? That way the information is not adding too much to the length of the article, and it's an opt-in to learn more about it.

That's my two cents.
In the docs team, we have an upcoming project to look into how we structure these upgrade docs, and hopefully make them a little easier to navigate.

I see the point @sofietoft but what I was aiming for here was a general introduction to upgrades that is worth reading before you dive into the detail. As I do see some confusion about what we are talking about when we discuss these. So rather than hiding it in an expandable section, if you feel this page is too long, I think I'd prefer moving what I've added to a new page and placing it before the existing one in the summary. Then you can dive straight into the detail if you know the background, but if not, you'll hopefully see this new content first.

Let's get @BoletteKern's view too though - as this I've put this together following a request she had having had some feedback on this topic.

Yes, splitting up is also a good idea! We can always highlight the page with a link from the article, as something we recommend going through before initiating the upgrade process.

We'll wait for Bolette, before we make any changes for now 🙏